Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / Transform Objects Reference

Functions / Getting and Setting the Clip

GXSetShapeClip

You can use the GXSetShapeClip function to change the clip property of a transform object associated with a specified shape.

void GXSetShapeClip(gxShape target, gxShape clip);

target

A reference to the shape whose transform object you want to change the clip shape of.

clip

A reference to a shape object containing the new clip shape information.

DESCRIPTION

The GXSetShapeClip function copies information from the shape object referenced by the clip parameter into the clip property of the transform object associated with the shape referenced by the target parameter.

Calling this function is almost equivalent to

GXSetTransformClip(GXGetShapeTransform(myShape),theClip);

except that, if the source shape's transform object is shared with other shapes, GXSetShapeClip creates a new copy of the transform object, attaches it to the source shape, and changes the clip of the copy. That way, calling this function does not produce side effects on other shapes.

You can specify nil for the clip parameter, in which case this function sets the clip property of the target shape's transform to a full clip (no transform clipping takes place).

The new clip shape, which you specify using the clip parameter, may be a geometric shape, a bitmap shape, or a glyph shape. It may not be a picture, text, or layout shape.

• If you specify a geometric shape, it must be in primitive form--that is, all the stylistic information about the shape must be incorporated into the shape's geometry--because this function copies only the geometry-related information from the shape you specify. It does not copy the information contained in the shape's style. You can convert a shape to its primitive form using the GXPrimitiveShape function, which is described in Inside Macintosh: QuickDraw GX Graphics.
• If you specify a bitmap shape, it must have a pixel size of 1 and its color profile reference must be nil. In the bitmap, pixel values of 0 obscure drawing; pixel values of 1 do not restrict visibility.
• If you specify a glyph shape, this function uses information from the glyph shape's style object as well as its style list to determine the size, form, and position of the glyph outlines; those outlines are then used to clip drawing. The style list cannot have nil entries. A style object referenced by the glyph shape cannot be complex--that is, it cannot have a cap, join, dash, pattern, text face, font variation, tag list, or any of the properties used only by layout shapes.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
transform_is_nil
shape_is_nil
shapeFill_not_allowed	(debugging version)
colorProfile_must_be_nil	(debugging version)
bitmap_pixel_size_must_be_1	(debugging version)
empty_shape_not_allowed	(debugging version)
ignorePlatformShape_not_allowed	(debugging version)
nil_style_in_glyph_not_allowed	(debugging version)
complex_glyph_style_not_allowed	(debugging version)
illegal_type_for_shape	(debugging version)
Warnings
tags_in_shape_ignored	(debugging version)
Notices (debugging version)
clip_already_set

SEE ALSO

To retrieve the clip property of a transform object associated with a particular shape, use the GXGetShapeClip function, described in the previous section.

To assign a clip directly to a transform object, use the GXSetTransformClip function, described on page 6-44.

For information about the clip property of transform objects, see "Clip" on page 6-7.

For information about primitive shapes, geometric shapes and bitmap shapes, see
Inside Macintosh: QuickDraw GX Graphics. For information about glyph shapes, see Inside Macintosh: QuickDraw GX Typography.